PD Collection CD 1/PD Collection CD 1.iso/programer2/icon/ReadMe

Text File | 1991-06-23 | 12KB | 311 lines

                   Icon version 8 for the Archimedes
                   ---------------------------------

There is very little here to say regarding this implementation of Icon
for the Archimedes. It conforms fully to the standard Icon version 8
documentation, ie. "The Icon Programming Language (2nd edition)" by R.E.
and M.T. Griswold.

This version of Icon supports

        * Large Integers
        * Co-expressions
        * Keyboard functions (getch, getche, kbhit)
        * The system() function

(which are the most often omitted features).

For the Archimedes, &features includes "Acorn Archimedes".


Environment variables
---------------------

Icon uses a number of environment variables to set run-time values such
as stack sizes or whether tracing is switched on. These are usually
given names such as

        MSTKSIZE                Main stack size
        TRACE                   Tracing on?

Following the usual Archimedes conventions, these variables have all
been renamed, by prefixing the name with "Icon$". So, the above
variables are called

        Icon$MStkSize           Main stack size
        Icon$Trace              Tracing on?

and similarly for all "start-up" environment variables.


File names
----------

As usual, the convention of using file name "extensions" causes
difficulties. Icon uses four file extensions, namely

        .icn                    Icon source code
        .u1                     Intermediate code (procedures)
        .u2                     Intermediate code (globals)
        .ux                     Linker diagnostics (-L flag)

Under RISC OS, the usual transformation is performed, ie. rather than
looking for "file.icn", Icont looks for "Icn.file" - ie, file "file" in
directory "Icn".

Similarly to Acorn C, Icont expects the U1 and U2 directories to be set
up in advance (and the Ux directory if -L is used). Also, note that an
"extension" of .icn can be omitted from the file name in Icont, so that
to compile and link "Icn.Hello", all you need is

        Icont hello

The convention of using an "extension of .u to mean .u1 and .u2 is
retained. So, to link U1.hello, U2.hello, U1.options and U2.options,
giving an output file called HelloW, all that is needed is

        Icont -o HelloW U.hello U.options

Note that, UNLIKE Acorn C, filenames cannot be written in the
"extension" form, so that

        Icont -o HelloW hello.u options.u

is WRONG.

Also, note that if compiling stdin (via Icont -, or simply Icont with no
parameters) the output files are U1.Stdin, U2.Stdin and Stdin (the
I-code executable).


Standard search path
--------------------

When looking for files named in "link" statements, Icon looks in places
specified in the IPATH environment variable (called Icon$Ipath on the
Archimedes). The default for this variable, when not set, is

        "Icon: Lib:Icon."

Icon therefore first looks along the RISC OS path specified by the OS
variable Icon$Path, and if the file is not found, it then looks for a
directory "Icon" on Lib$Path.

To alter the search path, two methods can be used. First, the value of
Icon$Ipath can be altered. In this case, the Icon form of path,
consisting of a space-separated list of directory prefixes, is used. An
alternative method is to leave the default IPATH, but set up a suitable
Icon$Path variable.

The second method is recommended, as it conforms better to the standard
conventions under RISC OS. (A third possibility, to install a directory
Icon somewhere on Lib$Path, is possible. This is a good idea for people
like me, who keep all their language run-time stuff somewhere on
Lib$Path).


File types
----------

Icont will timestamp the executable I-code file, giving it file type
"Icon" if such a file type exists. Ie, if <File$Type_xxx> is "Icon", for
any xxx, then the I-code file is given file type xxx. This allows users
to set up in their !Boot file

        Set File$Type_xxx       Icon
        Set Alias$@RunType_xxx  Iconx %0 %*1

to make icon I-code files directly executable. (The %*1 allows for
parameters being passed to the Icon program).


Pipes
-----

Archimedes Icon DOES support the opening of files as pipes (the "p"
mode). This is done using temporary files. The input or output of the
command is stored in a temporary file in one of the following places
(tried in this order)

        <Tmp$Dir>       if this OS variable is set, and the directory exists
        &.Tmp           if the directory exists
        @               ie, the current directory

The temporary filenames are generated using random names, and so will not
clash with existing files (hopefully!), and the temporary files will be
deleted when they are finished with.

The IO redirection is done using the C convention ("command <in >out")
for all but built-in commands (there is a hard-coded list of these). The
built-in commands use OS redirection ("command { < in > out }") and the
output file is post-processed to convert line separators "\r\n" into
just "\n", which is what Icon expects.

If you want to run a program which is NOT a built-in, but which does
not support the C convention (eg, basic or pascal programs), simply add
a '%' to the front of the command (ie "%command arg arg..."). OS
redirection will then be used, and the '%' removed. If you want to run
a command starting with a '%', and STILL use C redirection, "*%command"
should work (OS_CLI ignores leading asterisks).

Also, if you have the PD program "m4", which preprocesses files (giving
C-like #define and #include facilities, plus much more, but with a
different syntax), then you can use the "-m" flag to Icont, to
preprocess your Icon code using m4.


System Dependent Functions
--------------------------

Archimedes Icon includes a number of low-level RISC OS interface
functions, in a similar manner to MS-DOS ports of Icon. The relevant
functions are

1. Swi(swi,r0,r1,r2,...,r9)

   Swi(swi,r0,r1,r2,...,r9) is a general interface to the OS SWI
   functions. The inputs are a SWI number (or name), and the values of
   the registers r0 to r9. Any unused registers can be omitted. The
   "swi" parameter is treated as a SWI number if it is an integer, and
   a SWI name if it is a string. An invalid name results in run-time
   error 205 (value out of range), and any type other than integer or
   string results in run-time error 123 (invalid type).

   The registers, r0-r9, must be integer values. Any other type gives
   run-time error 123 (invalid type). These are assigned to the relevant
   register variables before the call. Note that an earlier version of
   Archimedes Icon allowed Icon strings to be passed as register
   parameters to Swi(). This is in fact highly insecure (due to the way
   Icon handles strings - some details of which I was unaware of at the
   time). In the current implementation, if you want to pass a string to
   Swi(), use GetSpace(), Peek() and Poke() (see below). Remember that
   Icon does not supply terminating NULL bytes on strings!

   If the SWI call fails (ie, an OS error occurs), Swi() fails (in the
   Icon sense). Otherwise, the return value is a 10-element list,
   holding the integer values of r0, ..., r9. To get at strings which
   are returned as pointers, see Peek() below.

   Note that Swi() should not corrupt Icon's internal structures,
   provided you pass the correct parameters to the swi. This was not
   true in the earlier version. Obviously, such tricks as passing a
   buffer, but lying about its length, will always cause problems! To
   get a safe buffer, use GetSpace(), below.

2. GetSpace(i)

   GetSpace(i) returns an integer, which is the address of a block of
   storage, i bytes long. The storage is claimed using malloc(), and is
   completely outside the control of Icon. The only way to read from or
   write to this area, is using Peek() and Poke(), below.

   GetSpace() fails (in the Icon sense) if the memory is unavailable
   (ie, malloc() returns NULL). This also happens if i is 0.

3. FreeSpace(a)

   FreeSpace(a) frees the block of storage at address a (which must be
   an integer), using free(). This should be used to free storage
   allocated using GetSpace(). No check is made to make sure that a is
   the address of an area claimed by GetSpace(). If it is not, you will
   almost surely crash Icon.

4. Peek(a,i)

   Peek(a,i) returns an Icon string, consisting of the i bytes at
   address a. Peek() does not move any data about. It simply builds an
   Icon string qualifier, pointing to the data. Hence the string
   returned by Peek() is not modifiable.

5. Poke(a,s)

   Poke(a,s) copies the Icon string s to address a. The string is copied
   directly, byte by byte, with no conversion. No terminating null byte
   is added. This is the only way of assigning data into a block of
   storage allocated using GetSpace().

6. Wildcard(l)

   Wildcard(l) takes a single string or a list of strings as its input
   parameter. It processes each string in turn, treating it as a
   filename which may contain wildcards. It expands the wildcards in the
   usual RISC-OS manner, and produces a list of all matching filenames.
   The return value from Wildcard() is a new list, containing the
   expanded versions of all the input strings. This is best explained by
   an example.

      Sources := Wildcard(["C.*", "H.*"])

   will assign to Sources a list of the filenames of all C source files
   in the current directory.

   The function will often be used to provide wild-card expansion of
   filenames specified on the command line of an Icon program. For
   example, the following short Icon program will set all files
   specified on the command line to "text" file type. It can be invoked
   as (for example) "maketext C.* H.*".

      procedure main(args)
         local file
         args := Wildcard(args)
         every file := !args do
            system("Settype " || file || " text")
      end

To go with these functions, &features includes "Archimedes extensions".


Implementation notes
--------------------

Unlike the standard Icon implementation, the C stack for a
co-expression is allocated from the heap, using malloc(). This is
necessary to support the built in Archimedes C stack extension
facilities. The C stack is freed along with the other co-expression
data structures. The code required to free the C stack relies on an
undocumented feature of the internal routine coswitch() - see the
source for details - and may not survive into future versions. It also
was not present in the previous version of this port.


Port information
----------------

This port was produced by

Paul Moore

10, Mulberry Rise,
Firdale Park,
Northwich,
Cheshire
CW8 4UQ

E-Mail: [e-mail]
        [e-mail]

I am interested in hearing about any bugs in the port, or any
suggestions for improvements (although I will not put in any Archimedes
specific alterations to the Icon language itself - I have registered
this port with the Icon project, so that any upgrades will be
automatically available).

This distribution may not include full source (depending upon where you
got it from). If not, I can supply source. Please contact me (including
a couple of FORMATTED disks), and I'll send a copy. Note: the sources
are held as Spark archives, so you'll need to have Spark or the PD
un-archiver SparkPlug to get at them. If you do not have SparkPlug
(version 2 is required), then let me know so that I can include it with
the distribution. The source requires Acorn's C, version 3.0, to
compile, plus the Acorn ObjAsm assembler (for the file Asm.Rswitch), if
you wish to include co-expressions. If you ask nicely, I can provide a
pre-assembled O.Rswitch when I distribute the code.

I also have the rest of the Icon distribution (the Icon program library,
Idol - an object-oriented front end for Icon, and a few other bits).
Again, contact me, including disks, if you want them.

Have fun with Icon - it's an unusual, but nice, language.

Paul Moore